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CALL-TYPE API TO SQL/DS WITH EXTERNALLY DESCRIBED OPERATIONS 



TEMPLATE (T) 



(Optional SQL table 
definition records) 



GET: SELECT . . . 
GETFIRST: SELECT . 
INSERT: INSERT • . . 
DELETE: DELETE . . . 
UPDATE: UPDATE ... 
CHG-DEPT: UPDATE 



QUERY_2: SELECT C1,C2 
FROM SQLDBA.Tl WHERE 
C3 = ?(CHAR,4); >' 



SYSTEM. 
SYSACCESS 



Access < 
Module 
T 



SQLDBA. SOD 
Table 



T/GET . . . 
T/GETNEXT. . . 

T/QUERY_2. . . 



TEMPLATE PROCESSING 
PROGRAM (CRTDBPGM) 




Put Template name (T) into "TPL" 
CREATE PROGRAM :TPL 
Do for each statement in T 
Scan statement 
Record stmt name, type* and 
type and length of each I/O 
and WHERE CLAUSE variable 
Edit stmt to remove name and 
embedded attributes of WHERE 
CLAUSE variables . 
Move edited stmt into variable 

iiQir 

PREPARE FROM :Q SETTING :S 

IN PROGRAM :TPL 
Build a control structure (SOD) 
for tpl/stmt combination and 
store in database (SOD TABLE) 



SQL/DS Tables 



Template Name: 
Statement Name: 
Stmt type: 
Stmtid: 
WHERE CLAUSE 

field count: 
Input/Output 

field count: 
C3 attributes: 
CI attributes: 
C2 attributes: 



T 

QUERY_2 
S 

26 



2 

CHAR U 
VARCHAR 8 
INTEGER <♦ 



End of do loop 



Fig. 1 



A method is described which specifies and names structured-query- 
language data-manipulation-language (SQL DML) operations independently 
from any of the programs that use them, a generalized SQL statement 
processor for generating access modules and other data structures used 
at run-time, and the run-time support itself. 

This method comprises: 
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CALL-TYPE API TO SQL/DS WITH EXTERNALLY DESCRIBED OPERATIONS - 
Continued 



APPLICATION 
PROGRAM (P) 



CALL GDBA(STARTLUW) >- 



CALL GDBA(GET) >- 



Note: SOD's 
are cached in 
memory after 
first access. 



SQLDBA. SOD 
Table 



T/GET. . . 
T/GETNEXT. 

T/QUERY_2 . 



Tpl Name (T) 

Stmt Name 
(QUERY_2) 

Lists of 
addresses 
of WHERE 
CLAUSE and 
I/O 

variables 



SYSTEM. 
SYSACCESS 



Access > 
Module 
T 



SQL/DS Tables 





DB NAME 









RUNTIME SUPPORT 
(GDBA) 



CALL FUNCTION: STARTLUW 



Do program initializa- 
tion and switch to new 
data base, if necessary « 



CALL FUNCTION: GET 



Build cursor name 

■T QUERY_2-' in 

host variable , C 
Get SOD control block 

for T/QUERY_2 
Get Stmtid from SOD and 

set in variable SI 
Store Tpl name in host 

variable PI 
DECLARE :C CURSOR FOR 

;SI IN PROGRAM :PI 

Build SQLDA for OPEN 
from WHERE CLAUSE 
field addr's & attr's 

OPEN :C 

Build SQLDA for FETCH 

from I/O field 

addresses & attributes 
FETCH :C USING 

DESCRIPTOR SQLDA 
CLOSE :C 



Fig. 2 

A method of specifying and processing SQL DML statements in a 
form external to the application programs that use them. A set of SQL 
statements is stored in a CMS t file called a 'template 1 . An SQL/DS 
table description is optionally placed in a template file, in which 
case a set of basic SQL statements to access data in that table are 
automatically generated and appended to the template file. 

A data structure called an SQL Operation Descriptor (SOD) pro- 
duced by the processing of a template. The SQL SOD contains informa- 
tion required at run-time. 

Two programs for processing the template files. 

An application programming interface (API) consisting of control 
functions and a set of data access functions referencing the SQL state- 
ments predefined in template files. 
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CALL-TYPE API TO SQL/DS WITH EXTERNALLY DESCRIBED OPERATIONS - 
Continued 

A run-time module which uses the SODs and parameters passed on 
calls to perform the data control and access functions. 

The environment and a program to initialize it. 

Template files contain one or multiple SQL statements, each of 
which is referenced by a name, A special type of template is used as 
input to a table-creation process. These are called 1 table templates 1 
and contain, possibly in addition to SQL DML statements, the descrip- 
tion of an SQL table to be created. Besides creating the SQL table, 
the table template processor also generates SQL statements which are 
appended to the template to do basic operations on the associated 
table. 

Each SQL statement in a template is prefixed by a name delimited 
by a ' : f . The SQL statements are coded in a form very similar to that 
of the extended dynamic form of SQL/DS DML, in which ? f s are used as 
place holders for host program input variables. 

In a table template, a table description is placed at the beginn- 
ing of the file, just following the header record which indicates the 
template name and type. Each table column (field) is represented by a 
row in the table definition section. That row specifies the column 
name, its data type, its length, whether it is a part of the table's 
unique index, and whether it can have a NULL value, 

THE SQL SOD STRUCTURE. The SOD data structure is used at run- 
time along with information stored in an SQL/DS access module to in- 
form a data base management system (DBMS) how to carry out a particu- 
lar operation. 

Information about the operands participating in any SQL DML opera- 
tion is passed to the DBMS in a data structure called SQLDA. The SOD 
and process for generating it provide certain required data at run- 
time. 

SODs as well as the associated access module are created by one 
of the template processing programs. The SOD contains: 

An operation-type code for validating that the SOD is used with 
the appropriate run- time function. 
- The associated statement number in the access module. 
A set of bit flags. 

The number of WHERE clause data items in the operation. 
The number of input or output data items in the operation. 
An array specifying the type and length of each operand. 

TEMPLATE PROCESSORS. Two programs for the processing of template 
files are CRTDBTBL and CRTDBPGM, The access module is identified by 
the name of the associated template, and the SODs are identified by 
the combination of template name and statement name. 
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CALL-TYPE API TO SQL/DS WITH EXTERNALLY DESCRIBED OPERATIONS - 
Continued 

CRTDBTBL creates a table in the SQL/DS data base based on the 
table description in the input file. It also creates a unique index 
for the table based on the table columns which are flagged as 'key' 
fields/ Using its knowledge of the table columns, it constructs a set 
of 'default 1 SQL statements to do the most basic operations that the 
programmer might want to do on the table. 

The other template processor, CRTDBPGM, produces two outputs. 
One output is an SQL/DS access module containing the access strategies 
for the processed template which SQL/DS uses at run-time. The other 
is a set of SODs, which are stored in a data base table. 

ENVIRONMENT INITIALIZATION PROGRAM . SQL/DS uses several differ- 
ent data areas in its interaction with application programs. Rather 
than re-allocating these for each program invocation or SQL operation, 
a program is provided that Initializes the required environment. It 
pre-allocates these areas as well as another communication area one 
time, and they are retained and re-used throughout the existence of 
this environment. 

RUN-TIME SUPPORT. The run-time program accepts a variable length 
list of parameters which includes a function code, and, for most func- 
tions, the identification of a template and statement within that 
template. Where required, the addresses of host program input and 
output variables are also passed. 

The following functions are .supported by the run-time program: 

Start logical unit of work (LUW) . While the concept of an LUW is 

an integral part of SQL/DS, normally LUWs are implicitly started. 

This function is provided because an initialization procedure is 

required for each LUW. A parameter passed on this function call 

specifies the name of the SQL data base desired for the LUW. 

This allows the application program to dynamically switch data 

bases when desired and provides a way for the run-time support to 

insure that the user or some other program has not switched data 

bases unbeknown to the application program. This data base 

checking is bypassed, if desired. 

The SQL COMMIT WORK operatiQn. 

The SQL COMMIT WORK RELEASE operation. 

The SQL ROLLBACK WORK operation. 

The SQL ROLLBACK WORK RELEASE operation. 

Get SOD. This provides advanced application programs access to 
the SOD for a particular operation. 
- GET a single row from the data base. 

GET FIRST row of a set of rows from the data base. 
GET NEXT row of a set of rows from the data base. 
INSERT a row into the data base. 

UPDATE selected fields in one or more rows of the data base. 
DELETE one or more rows from the data base. 
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CALL-TYPE API TO SQL/DS WITH EXTERNALLY DESCRIBED OPERATIONS - 
Continued 

Rather than exposing special indicator values to the application 
program for flagging null column values, nulls are encoded and decoded 
by the run-time program to and from special unique values such as, in 
the case of integers, the largest possible negative value, 

PSEUDO-CODE FOR OPERATION. Figs. 1 and 2, respectively, show 
pseudo-code examples for the processing of a template and the execu- 
tion of an application program using the outputs resulting from that 
processing. 
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